<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <title>CruiseControl.NET : Executable Task</title>
	    <link rel="stylesheet" href="styles/site.css" type="text/css" />
        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">	    
    </head>

    <body>
	    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
		    <tr>
			    <td valign="top" class="pagebody">
				    <div class="pageheader">
					    <span class="pagetitle">
                            CruiseControl.NET : Executable Task
                                                    </span>
				    </div>
				    <div class="pagesubheading">
					    This page last changed on Jun 26, 2009 by <font color="#0050B2">csut017</font>.
				    </div>

				    <p>The Executable Task lets you invoke any command line executable. It doesn't offer as much specific integration as (for example) the <a href="NAnt Task.html" title="NAnt Task">NAnt Task</a>, but does allow you to hook almost anything up as a build process to CCNet.  CCNet will examine the exit code when the executable ends and act accordingly.</p>

<h4><a name="ExecutableTask-Examples"></a>Examples</h4>

<p>Minimalist example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;exec executable=<span class="code-quote">"c:\projects\myproject\build.bat"</span>/&gt;</span></pre>
</div></div>
<p>Full example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;exec&gt;</span>
    <span class="code-tag">&lt;executable&gt;</span>make<span class="code-tag">&lt;/executable&gt;</span>
    <span class="code-tag">&lt;baseDirectory&gt;</span>D:\dev\MyProject<span class="code-tag">&lt;/baseDirectory&gt;</span>
    <span class="code-tag">&lt;buildArgs&gt;</span>all<span class="code-tag">&lt;/buildArgs&gt;</span>
    <span class="code-tag">&lt;buildTimeoutSeconds&gt;</span>10<span class="code-tag">&lt;/buildTimeoutSeconds&gt;</span>
    <span class="code-tag">&lt;successExitCodes&gt;</span>0,1,3,5<span class="code-tag">&lt;/successExitCodes&gt;</span>
    <span class="code-tag">&lt;environment&gt;</span>
        <span class="code-tag">&lt;variable&gt;</span>
            <span class="code-tag">&lt;name&gt;</span>MyVar1<span class="code-tag">&lt;/name&gt;</span>
            <span class="code-tag">&lt;value&gt;</span>Var1Value<span class="code-tag">&lt;/value&gt;</span>
        <span class="code-tag">&lt;/variable&gt;</span>
        <span class="code-tag">&lt;variable name=<span class="code-quote">"MyVar2"</span> value=<span class="code-quote">"Var2Value"</span>/&gt;</span>
        ...
    <span class="code-tag">&lt;/environment&gt;</span>
<span class="code-tag">&lt;/exec&gt;</span></pre>
</div></div>

<h4><a name="ExecutableTask-ConfigurationElements%3A"></a>Configuration Elements:</h4>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Node </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Required </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Version </th>
</tr>
<tr>
<td class='confluenceTd'> executable </td>
<td class='confluenceTd'> The path of the program to run. If this is relative, then must be relative to either (a) the base directory, (b) the CCNet Server application, or (c) if the path doesn't contain any directory details then can be available in the system or application's 'path' environment variable </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> true </td>
<td class='confluenceTd'> n/a </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> baseDirectory </td>
<td class='confluenceTd'> The directory to run the process in. If relative, is a subdirectory of the <a href="Project Configuration Block.html#ProjectConfigurationBlock-workingDirectory">Project Working Directory</a> </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> <a href="Project Configuration Block.html#ProjectConfigurationBlock-workingDirectory">Project Working Directory</a> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> buildArgs </td>
<td class='confluenceTd'> Any command line arguments to pass in </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> no arguments </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> buildTimeoutSeconds </td>
<td class='confluenceTd'> Number of seconds to wait before assuming that the process has hung and should be killed. </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> 600 (10 minutes) </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> successExitCodes </td>
<td class='confluenceTd'> A comma-separated list of exit codes that indicate success. </td>
<td class='confluenceTd'> list of ints </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> 0 </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> environment </td>
<td class='confluenceTd'> Specifies any environment variables to set for the executable. </td>
<td class='confluenceTd'> complex </td>
<td class='confluenceTd'> false <br clear="all" /> </td>
<td class='confluenceTd'> (none) </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> description </td>
<td class='confluenceTd'> If filled in, this will be shown in the buildstage as the process name <br clear="all" /> </td>
<td class='confluenceTd'> string <br clear="all" /> </td>
<td class='confluenceTd'> false <br clear="all" /> </td>
<td class='confluenceTd'> n/a </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> dynamicValues </td>
<td class='confluenceTd'> Any dynamic parameters to be used. See <a href="Dynamic Parameters.html" title="Dynamic Parameters">Dynamic Parameters</a> </td>
<td class='confluenceTd'> Dynamic values array - see <a href="Dynamic Parameters.html" title="Dynamic Parameters">Dynamic Parameters</a> </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> <em>None</em> </td>
<td class='confluenceTd'> 1.5.0 </td>
</tr>
</tbody></table>

<h3><a name="ExecutableTask-IntegrationProperties"></a>Integration Properties</h3>

<p>The following parameters are passed to the external program using environment variables, in addition to those you specify in the &lt;environment&gt; element.:</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Label </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Example </th>
<th class='confluenceTh'> Version </th>
</tr>
<tr>
<td class='confluenceTd'> CCNetBuildCondition </td>
<td class='confluenceTd'> The condition used to trigger the build, indicating if the build was triggered by new modifications or if it was forced.  Legal values are: "IfModificationExists" or "ForceBuild" </td>
<td class='confluenceTd'> ForceBuild </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetIntegrationStatus </td>
<td class='confluenceTd'> The status of the current integration. Could be Success, Failure, Exception or Unknown </td>
<td class='confluenceTd'> Success </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetLabel </td>
<td class='confluenceTd'> The label used to identify the CCNet build.  This label is generated by the CCNet labeller. </td>
<td class='confluenceTd'> 1.0.2.120 </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetLastIntegrationStatus </td>
<td class='confluenceTd'> The status of the previous integration. Could be Success, Failure, Exception or Unknown </td>
<td class='confluenceTd'> Success </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetProject </td>
<td class='confluenceTd'> The name of the CCNet project that is being integrated. </td>
<td class='confluenceTd'> MyProject </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetBuildDate </td>
<td class='confluenceTd'> The date of the build (in yyyy-MM-dd format) </td>
<td class='confluenceTd'> 2005-08-10 </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetBuildTime </td>
<td class='confluenceTd'> The time of the start of the build (in HH:mm:ss format) </td>
<td class='confluenceTd'> 08:45:12 </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetArtifactDirectory </td>
<td class='confluenceTd'> The <a href="Project Configuration Block.html#ProjectConfigurationBlock-artifactDirectory">project artifact directory</a> (as an absolute path) </td>
<td class='confluenceTd'> <tt>c:\program files\CruiseControl.NET\Server\MyProject\Artifacts</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetWorkingDirectory </td>
<td class='confluenceTd'> The <a href="Project Configuration Block.html#ProjectConfigurationBlock-workingDirectory">project working directory</a> (as an absolute path) </td>
<td class='confluenceTd'> <tt>c:\program files\CruiseControl.NET\Server\MyProject\WorkingDirectory</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetRequestSource </td>
<td class='confluenceTd'> The source of the integration request; this will generally be the name of the trigger that raised the request. </td>
<td class='confluenceTd'> IntervalTrigger </td>
<td class='confluenceTd'> 1.1.0 </td>
</tr>
<tr>
<td class='confluenceTd'> CCNetFailureUsers </td>
<td class='confluenceTd'> The list of users who have contributed modifications to a sequence of builds that has failed. </td>
<td class='confluenceTd'> John, Smith<br clear="all" /> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetListenerFile </td>
<td class='confluenceTd'> <a href="http://confluence.public.thoughtworks.org/display/CCNETCOMM/Viewing+build+progress+with+Nant+and+MSBuild">Viewing build progress with Nant and MSBuild</a> </td>
<td class='confluenceTd'> c:\Project\Artifact\listener.xml </td>
<td class='confluenceTd'> 1.4.0 </td>
</tr>
<tr>
<td class='confluenceTd'> CCNetProjectUrl </td>
<td class='confluenceTd'> The URL where the project is located </td>
<td class='confluenceTd'> <a href="http://myhost/ccnet/server/">http://myhost/ccnet/server/</a> </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetNumericLabel </td>
<td class='confluenceTd'> Contains the label as an integer if conversion is possible, otherwise zero. </td>
<td class='confluenceTd'> 1 </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetModifyingUsers <br clear="all" /> </td>
<td class='confluenceTd'> The list of users who have contributed to the current build only <br clear="all" /> </td>
<td class='confluenceTd'> Smith </td>
<td class='confluenceTd'>&nbsp;</td>
</tr>
<tr>
<td class='confluenceTd'> CCNetUser </td>
<td class='confluenceTd'> The user who forced the build. If security is off, or the build is not forced, then this will not be set. </td>
<td class='confluenceTd'> John Doe </td>
<td class='confluenceTd'> 1.5.0 </td>
</tr>
</tbody></table>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Windows seems to change the case of environment variables occasionally. If your task target doesn't find one of these properties, try using all upper case or all lower case versions of these properties.</td></tr></table></div>

<h3><a name="ExecutableTask-Exitcodes"></a>Exit codes</h3>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Code </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> CCNet Behavior </th>
</tr>
<tr>
<td class='confluenceTd'> a code in &lt;successExitCodes&gt; </td>
<td class='confluenceTd'> Success </td>
<td class='confluenceTd'> The build continues </td>
</tr>
<tr>
<td class='confluenceTd'> &#45;1 </td>
<td class='confluenceTd'> Timed out </td>
<td class='confluenceTd'> The operation timed out and the build fails </td>
</tr>
<tr>
<td class='confluenceTd'> other </td>
<td class='confluenceTd'> Failure </td>
<td class='confluenceTd'> The build fails </td>
</tr>
</tbody></table>

<h3><a name="ExecutableTask-FrequentlyAskedQuestions"></a>Frequently Asked Questions</h3>

<p><b>Does the exec task pass the integration properties via the command line?</b></p>

<p>No.  The integration properties are only available as environment variables.  As there is no way of knowing the way in which the external program expects these properties to be formatted as command line arguments, environment variables are a simple, common medium for making these values accessible.  To pass these environment variables into an external program, have the exec task call a batch file instead that will pick up the environment variables, format them and pass them as command line arguments to the external program.</p>

<p><b>Using built in shell commands</b><br/>
In Windows use <em>cmd.exe</em> as the executable, and pass the wanted command as an argument, preceded with <em>/c</em> This allows to execute del &#42;.&#42; and the like.<br/>
see also <a href="http://www.ss64.com/nt/cmd.html">Command help</a></p>

<p>example :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;exec&gt;</span>
     <span class="code-tag">&lt;executable&gt;</span>c:\Windows\System32\cmd.exe<span class="code-tag">&lt;/executable&gt;</span>
     <span class="code-tag">&lt;buildArgs&gt;</span>/C NET STOP <span class="code-quote">"Service name"</span><span class="code-tag">&lt;/buildArgs&gt;</span>
  <span class="code-tag">&lt;/exec&gt;</span></pre>
</div></div>
<p><br clear="all" /></p>

				    
                    			    </td>
		    </tr>
	    </table>
	    <table border="0" cellpadding="0" cellspacing="0" width="100%">
			<tr>
				<td height="12" background="http://confluence.public.thoughtworks.org//images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
			</tr>
		    <tr>
			    <td align="center"><font color="grey">Document generated by Confluence on Sep 29, 2009 20:59</font></td>
		    </tr>
	    </table>
    </body>
</html>